SDK (Software Development Kit) — это набор инструментов для разработки собственных приложений. Wialon SDK включает в себя несколько API. Самым базовым из них является Remote API, на изучение которого нацелены данные статьи. Remote API предполагает доступ к данным через HTTP-запросы и актуален для 1С, PHP, C++/C# и других языков программирования. JS API и остальные построены на базе Remote API.

В данной статье будут рассмотрены базовые знания, необходимые новичкам для использования Remote API.

Просмотр запросов в браузере

В начале изучения SDK часто возникает необходимость понять, какой API-запрос отправляется на сервер при совершении того или иного действия в интерфейсе Wialon. Это можно легко отследить, используя встроенные инструменты браузера для мониторинга сетевых запросов.

В браузере Chrome для этого используется вкладка Сеть из Инструментов разработчика, которые открываются при нажатии на клавишу F12. В других браузерах данный инструмент может открываться иначе, о чем можно прочитать в документации браузера.

При просмотре сетевых запросов можно увидеть отправляемый запрос, его параметры и ответ от API-сервера в формате JSON.

Формат запроса

Запросы HTTP отправляются на сервер в следующем формате:

https://host/wialon/ajax.html?svc=НАИМЕНОВАНИЕ_ЗАПРОСА¶ms={ПАРАМЕТРЫ}&sid=ИДЕНТИФИКАТОР_СЕССИИ

Получение токена и авторизация

Для авторизации в Wialon используется токен, то есть ключ, применяемый для зашифрованной идентификации пользователя.

Для создания токена можно использовать форму oAuth. После успешного логина токен отобразится в адресной строке браузера в качестве значения параметра access_token. При этом важно учитывать дополнительные параметры, которые регулируют такие свойства, как срок жизни (параметр duration), имя пользователя (параметр user), права доступа (параметр access_type) и другие.

Пример расширенной формы для получения токена:

https://hosting.wialon.com/login.html?client_id=ИМЯ_ПРИЛОЖЕНИЯ&access_type=256&activation_time=0&duration=0&lang=ru&flags=0&user=ИМЯ_ПОЛЬЗОВАТЕЛЯ

Пример ответа:

https://hosting.wialon.com/login.html?lang=ru&user=ИМЯ_ПОЛЬЗОВАТЕЛЯ&wialon_sdk_url=https%3A%2F%2Fhst%2Dapi%2Ewialon%2Ecom&access_token=ЗНАЧЕНИЕ_ТОКЕНА&svc_error=0

После получения токена его нужно использовать для авторизации. Пример логина под токеном:

https://hst-api.wialon.com/wialon/ajax.html?&svc=token/login¶ms={"token":"ЗНАЧЕНИЕ_ТОКЕНА"}

В ответе на логин под токеном содержится параметре eid, значение которого является уникальным идентификатором сессии. Далее он будет использоваться практически во всех API-запросах.

Настройка часового пояса

По умолчанию при работе c Remote API данные отображаются согласно часовому поясу GMT+0. Чтобы изменить его на необходимый, используется запрос render/set_locale. Достаточно выполнить данный запрос в рамках одной активной сессии.

При отправке запроса render/set_locale необходимо использовать параметр tzOffset. Стандартный метод вычисления его значения описан в документации.

Также узнать необходимое значение параметра tzOffset можно с помощью просмотра сетевых запросов в момент изменения часового пояса пользователя в веб-интерфейсе.

Системный ID

В API работа почти со всеми элементами ведется через внутренние идентификаторы, называемые системными ID, которые представлены уникальными цифровыми значениями.

В веб-интерфейсах системные ID по умолчанию не отображаются, но их можно увидеть тремя методами:

1. В ответе на запрос поиска элементов по критериям (core/search_items). Он будет рассмотрен подробнее в следующем разделе данной статьи.
2. В параметрах запросов при просмотре сетевых запросов в браузере.

3. В столбце avl_id в системе управления.

   Чтобы столбец avl_id отображался, необходимо авторизоваться в CMS, добавив в конец ссылки ?features=avl_id. Пример такой ссылки приведен на изображении ниже.
   
   

Поиск элементов по критериям

Данный запрос позволяет найти элементы по указанным в параметрах критериям.

Поиск осуществляется по следующим типам элементов, которые указываются в поле itemsType:

• avl_hw — тип устройства;
• avl_resource — ресурс;
• avl_retranslator — ретранслятор;
• avl_unit — объект;
• avl_unit_group — группа объектов;
• user — пользователь;
• avl_route — маршрут.

Одним из возможных критериев поиска могут являться подэлементы. В таком случае для параметра propType устанавливается значение propitemname, а параметр propName будет принимать следующие значения:

• объекты:
  • unit_sensors — датчики;
  • unit_commands — команды;
  • service_intervals — интервалы техобслуживания;
    
    
• ресурсы:
  • drivers — водители;
  • driver_groups — группы водителей;
  • jobs — задания;
  • notifications — уведомления;
  • trailers — прицепы;
  • trailer_groups — группы прицепов;
  • zones_library — геозоны;
  • reporttemplates — шаблоны отчетов;
  • orders — заявки;
    
    
• маршруты:
  • rounds — рейсы;
  • route_schedules — расписания;
    
    
• ретрансляторы:
  • retranslator_units — ретранслируемые объекты;
    
    
• объекты, пользователи или ресурсы:
  • custom_fields — произвольные поля;
  • admin_fields — административные поля.

Информация в ответе зависит от того, какие флаги указаны в запросе поиска в параметре flags. Флаги задаются в формате DEC.

Рассмотрим несколько примеров использования запроса о поиске элементов по критерию (другие примеры можно найти в документации).

Поиск элементов с определенным именем

Необходимо получить список всех доступных пользователю объектов, в имени которых есть слово Tractor, а также информацию о датчиках, созданных в объектах.

В таком случае можно использовать следующий запрос:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"avl_unit","propName":"sys_name","propValueMask":"*Tractor*","sortType":"sys_name"},"force":1,"flags":4097,"from":0,"to":0}&sid=ИДЕНТИФИКАТОР_СЕССИИ

{
	"searchSpec":{
		"itemsType":"avl_unit",
		"propName":"sys_name",
		"propValueMask":"*Tractor*",
		"sortType":"sys_name",
		"propType":"",
		"or_logic":"0"
	},
	"dataFlags":4097,
	"totalItemsCount":1,
	"indexFrom":0,
	"indexTo":0,
	"items":[
		{
			"nm":"Tractor 1",
			"cls":2,
			"id":22353120,
			"mu":0,
			"sens":{
				"1":{
					"id":1,
					"n":"Ignition",
					"t":"engine operation",
					"d":"",
					"m":"On\/Off",
					"p":"in1",
					"f":0,
					"c":"{\"act\":1,\"appear_in_popup\":true,\"ci\":{},\"cm\":1,\"mu\":0,\"pos\":2,\"show_time\":false,\"timeout\":0}",
					"vt":0,
					"vs":0,
					"tbl":[]
				},
				"2":{
					"id":2,
					"n":"Fuel level",
					"t":"fuel level",
					"d":"",
					"m":"l",
					"p":"adc1",
					"f":0,
					"c":"{\"act\":1,\"appear_in_popup\":true,\"calc_fuel\":0,\"ci\":{},\"cm\":1,\"fuel_params\":{\"fillingsJoinInterval\":300,\"filterQuality\":0,\"flags\":0,\"ignoreStayTimeout\":10,\"minFillingVolume\":20,\"minTheftTimeout\":0,\"minTheftVolume\":10,\"theftsJoinInterval\":300},\"mu\":0,\"pos\":1,\"show_time\":false,\"timeout\":0}",
					"vt":0,
					"vs":0,
					"tbl":[]
				}
			},
			"sens_max":-1,
			"uacl":-1
		}
	]
}

Поиск пользователей, созданных после определенной даты

Необходимо получить список пользователей, которые были созданы после 23 февраля 2021 05:41:46 (GMT+0). В ответе должны содержаться системные ID данных пользователей и их адреса электронной почты.

В таком случае можно использовать следующий запрос:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"user","propName":"rel_creation_time","propValueMask":">=1614058906","sortType":"sys_name"},"force":1,"flags":3,"from":0,"to":0}&sid=ИДЕНТИФИКАТОР_СЕССИИ

Поиск объектов определенного типа

Необходимо вывести список объектов с типом оборудования Wialon Retranslator, которые отправляли сообщения после 12 февраля 2023 12:00:00 (GMT+0). В ответе необходимо отобразить датчики объектов, время последнего сообщения и местоположения.

В таком случае можно использовать следующий запрос:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"avl_unit","propName":"rel_hw_type_name,rel_last_msg_date","propValueMask":"Wialon%20Retranslator,>1676203200","sortType":"rel_creation_time"},"force":1,"flags":1,"from":0,"to":0}&sid=ИДЕНТИФИКАТОР_СЕССИИ

Поиск объектов по имени датчика

Необходимо вывести список объектов, в которых создан датчик с именем Engine.

В таком случае можно использовать следующий запрос:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"avl_unit","propType":"propitemname","propName":"unit_sensors","propValueMask":"Engine","sortType":"sys_name"},"force":1,"flags":1,"from":0,"to":0}&sid=ИДЕНТИФИКАТОР_СЕССИИ

Поиск групп объектов по нескольким критериям

Необходимо получить список групп объектов, которые были созданы пользователем User, и в которые добавлено более 5 объектов.

В таком случае можно использовать следующий запрос:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"avl_unit_group","propName":"rel_user_creator_name,rel_group_unit_count","propValueMask":"User,>5","sortType":"sys_name"},"force":1,"flags":133,"from":0,"to":0}&sid=ИДЕНТИФИКАТОР_СЕССИИ

Список частых ошибок

Ошибка отображается в случае невозможности выполнить запрос. Полный список возвращаемых ошибок можно найти в документации.

Наиболее частыми ошибками являются:

• {error: 1} — недействительная сессия.
  Данная ошибка отображается, когда истек срок действия уникального идентификатора сессии. Чтобы исправить ошибку, достаточно выполнить логин под токеном еще раз и использовать новый идентификатор сессии (sid) для выполнения запросов.

  Если в течение 5 минут в рамках сессии не выполняется ни одного запроса, то она становится неактивной. Чтобы поддерживать сессию, вы можете каждые 5 минут отправлять запрос avl_evts.

• {error: 4} — неверный ввод.
  Данная ошибка отображается, если в тексте запроса присутствует ошибка: указаны не все требуемые параметры, текстовые параметры не заключены в кавычки, нет открывающей или закрывающей скобки и т. д. Чтобы исправить ошибку, необходимо исправить текст выполняемого запроса согласно его описанию в документации.
  
  
• {error: 7} — доступ запрещен.
  Данная ошибка отображается, если у пользователя недостаточно прав на выполнение запроса. Чтобы исправить ошибку, необходимо проверить, достаточно ли прав у токена, который используется для получения уникального идентификатора сессии, а также достаточно ли у пользователя, для которого был сгенерирован токен, прав в отношении используемых элементов.

Екатерина Гриб,Инженер Customer Service 2023-07-18

В данной статье будет рассмотрено создание учетных записей и объектов при помощи Remote API. Эти элементы являются ключевыми при работе с Wialon, а их создание требует выполнения цепочки обязательных действий.

Создание учетной записи

Перед выполнением данного действия необходимо вспомнить два важных термина:

• Создатель — это пользователь, от имени которого создан определенный элемент системы.
• Учетная запись — это макроэлемент системы, который представляет собой единство ресурса, пользователя и тарифного плана.

Исходя из этого, чтобы создать учетную запись, необходимо:

1. Найти подходящий тарифный план.
2. Найти системный ID пользователя-создателя, под которым будет находиться будущий создатель учетной записи.
3. От имени найденного пользователя создать нового пользователя.
4. От имени нового пользователя создать ресурс.
5. Объединить нового пользователя, ресурс и тарифный план в учетную запись.

Рассмотрим запросы, которые понадобятся на каждом из этих шагов, на следующем примере: необходимо создать учетную запись с именем sdk_account, которая по иерархии сервиса будет находиться под учетной записью пользователя manager.

1. Поиск тарифного плана

Используем запрос core/get_account_data.

https://hst-api.wialon.com/wialon/ajax.html?svc=core/get_account_data¶ms={"type":1}&sid=ИДЕНТИФИКАТОР_СЕССИИ

Имена назначенных тарифных планов будут отображаться в ответе на запрос в параметре subPlans. Предположим, что мы будем использовать тарифный план с именем standard_client.

2. Поиск системного ID пользователя-создателя

Используем запрос core/search_items.

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"user","propName":"sys_name","propValueMask":"manager","sortType":"sys_name"},"force":1,"flags":1,"from":0,"to":0}&sid=ИДЕНТИФИКАТОР_СЕССИИ

Системный ID пользователя будет отображаться в ответе на запрос в параметре id. Предположим, он будет иметь значение 11111.

3. Создание нового пользователя

Используем запрос core/create_user.

https://hst-api.wialon.com/wialon/ajax.html?svc=core/create_user¶ms={"creatorId":11111,"name":"sdk_account","password":"Pa%24%24w0rd","dataFlags":1}&sid=ИДЕНТИФИКАТОР_СЕССИИ

Системный ID пользователя будет отображаться в ответе на запрос в параметре id. Предположим, он будет иметь значение 22222.

4. Создание ресурса

Используем запрос core/create_resource.

https://hst-api.wialon.com/wialon/ajax.html?svc=core/create_resource¶ms={"creatorId":22222,"name":"sdk_account","dataFlags":1,"skipCreatorCheck":0}&sid=ИДЕНТИФИКАТОР_СЕССИИ

Системный ID ресурса будет отображаться в ответе на запрос в параметре id. Предположим, он будет иметь значение 33333.

5. Объединение в учетную запись

Используем запрос account/create_account.

https://hst-api.wialon.com/wialon/ajax.html?svc=account/create_account¶ms={"itemId":33333,"plan":"standard_client"}&sid=ИДЕНТИФИКАТОР_СЕССИИ

Создание объекта

Чтобы создать объект с помощью Remote API, необходимо:

1. Найти системный ID типа оборудования.
2. Найти системный ID пользователя-создателя, в учетной записи которого будет находиться будущий объект.
3. Создать объект.
4. Присвоить объекту уникальный ID.

Рассмотрим необходимые запросы на следующем примере: необходимо создать объект Delivery truck с типом оборудования Wialon IPS и уникальным ID 12345 в учетной записи пользователя sdk_account.

1. Поиск системного ID типа оборудования

Используем запрос core/get_hw_types.

https://hst-api.wialon.com/wialon/ajax.html?svc=core/get_hw_types¶ms={"filterType":"name","filterValue":["Wialon%20IPS"],"includeType":0,"ignoreRename":1}&sid=ИДЕНТИФИКАТОР_СЕССИИ

Системный ID типа оборудования будет отображаться в ответе на запрос в параметре id. Предположим, он будет иметь значение 44444.

2. Поиск системного ID пользователя-создателя

Используем запрос core/search_items.

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"user","propName":"sys_name","propValueMask":"sdk_account","sortType":"sys_name"},"force":1,"flags":1,"from":0,"to":0}&sid=ИДЕНТИФИКАТОР_СЕССИИ

Системный ID пользователя будет отображаться в ответе на запрос в параметре id. Предположим, он будет иметь значение 22222.

3. Создание объекта

Используем запрос core/create_unit.

https://hst-api.wialon.com/wialon/ajax.html?svc=core/create_unit¶ms={"creatorId":22222,"name":"Delivery%20truck","hwTypeId":"44444","dataFlags":1}&sid=ИДЕНТИФИКАТОР_СЕССИИ

Системный ID объекта будет отображаться в ответе на запрос в параметре id. Предположим, он будет иметь значение 55555.

4. Указание уникального ID

Используем запрос unit/update_device_type.

https://hst-api.wialon.com/wialon/ajax.html?svc=unit/update_device_type¶ms={"itemId":55555,"deviceTypeId":"44444","uniqueId":"12345"}&sid=ИДЕНТИФИКАТОР_СЕССИИ

Екатерина Гриб,Инженер Customer Service 2023-07-26

В данной статье будет рассмотрена работа с шаблонами отчетов при помощи Remote API. Выполнение отчетов через SDK подразумевает последовательность обязательных действий, которые не заметны при работе в веб-интерфейсе. Для полноты картины будут приведены примеры работы с отчетами с группировкой и без группировки.

Создание отчетов

В большинстве случаев пользователи создают шаблоны отчетов в веб-интерфейсе и потом выполняют их с помощью API-запросов. Далее мы будем рассматривать именно такие случаи.

Однако создание шаблонов отчетов доступно и через SDK, для чего нужно использовать запрос report/update_report.

Последовательность действий

Для получения результатов отчетов с помощью Remote API необходимо отправить несколько запросов подряд. Использование некоторых из них зависит от наличия группировки в отчете и количества анализируемых данных. Приведем самый общий список действий:

1. Авторизация через запрос token/login и настройка локализации через запрос render/set_locale.
   
   

2. Получение необходимых системных ID для:

   • элемента, для которого необходимо выполнить отчет;

     Так как отчеты могут выполняться по водителям, прицепам, пассажирам, геозонам и их группам, то в некоторых случаях также потребуется получить системные ID этих подэлементов.

   • ресурса, в котором содержится шаблон отчета;
   • самого шаблона отчета.
     
     

3. Выполнение отчета через запрос report/exec_report.

   В общем случае мы рекомендуем выполнять отчет в фоновом режиме на сервере. Несмотря на увеличение количества шагов, это бывает полезно, если отчет может выполняться долго из-за большого количества объектов, интервала выполнения отчета, количества таблиц и графиков и т. д. Далее в статье будет рассмотрено именно выполнение отчета в фоновом режиме.
   
   Если отчет выполняется не в фоновом режиме на сервере, то ответ на данный запрос будет аналогичен ответу из шага 5, поэтому далее можно сразу переходить к шагу 6.

4. Проверка статуса выполнения отчета через запрос report/get_report_status.
   После подтверждения готовности отчета можно будет продолжать движение по инструкции.
   
   
5. Получение результата отчета через запрос report/apply_report_result.
   Результат данного запроса предоставит количество строк, столбцов и уровней вложенности при наличии группировки.
   
   
6. Получение строк таблицы через запрос report/get_result_rows для отчета без группировки или через запрос report/select_result_rows для отчета с группировкой.
   Выбор таблицы, уровней вложенности и отображаемых строк осуществляется на основе данных из ответа на предыдущий запрос.
   
   
7. Экспорт в файл через запрос report/export_result.
   Данный шаг является необязательным, но достаточно несложным и полезным, поэтому мы рассмотрим и его.
   
   
8. Удаление результата предыдущего отчета через запрос report/cleanup_result.
   Данный шаг является обязательным, если в одной сессии необходимо выполнить несколько отчетов.

Далее рассмотрим два примера работы с отчетами (без группировки и с группировкой).

Работа с отчетом без группировки

Необходимо получить результаты выполнения отчета Список поездок, доступного авторизованному по токену пользователю, для объекта Грузовик 0769 (системный ID 55555) за интервал времени с 2023 Июнь 30 20:00 до 2023 Июль 01 03:59 (GMT+0) в виде ответа на API-запрос и PDF-файла.

В веб-интерфейсе результат выглядит следующим образом:

1. Авторизация и настройка локализации

Используем запрос token/login.

https://hst-api.wialon.com/wialon/ajax.html?svc=token/login¶ms={"token":"ЗНАЧЕНИЕ_ТОКЕНА"}

Более подробно авторизация описана в одной из предыдущих статей.

Настройка локализации включает в себя установку часового пояса (она также была рассмотрена ранее), формата даты и других параметров.

Используем запрос render/set_locale.

https://hst-api.wialon.com/wialon/ajax.html?svc=render/set_locale¶ms={"tzOffset":134217728,"language":"ru","formatDate":"%25E.%25m.%25Y%20%25H:%25M:%25S"}&sid=ИДЕНТИФИКАТОР_СЕССИИ

2. Получение системных ID

В одной из предыдущих статей мы уже описывали, как выполнять поиск элементов по критериям, поэтому сейчас обратим внимание только на поиск ресурса и шаблона отчета.

Получим список всех ресурсов, в которых создан шаблон отчета с именем Список поездок, доступных пользователю, для которого выполнена авторизация по токену. Используем запрос core/search_items:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"avl_resource","propType":"propitemname","propName":"reporttemplates","propValueMask":"Список%20поездок","sortType":"sys_name"},"force":1,"flags":8193,"from":0,"to":0}&sid=ИДЕНТИФИКАТОР_СЕССИИ

{
	"searchSpec":{
		"itemsType":"avl_resource",
		"propName":"reporttemplates",
		"propValueMask":"Список поездок",
		"sortType":"sys_name",
		propType:"propitemname",
		or_logic:"0"
		},
	"dataFlags":8193,
	"totalItemsCount":1,
	"indexFrom":0,
	"indexTo":0,
	"items":[
		{
			"nm":"sdk_account",
			"cls":3,
			"id":12345678,
			"mu":0,
			"rep":{
				1:{
					"id":1,
					"n":"Список поездок",
					"ct":"avl_unit",
					"c":59352
				},
				2:{
					"id":2,
					"n":"Поездки с группировкой",
					"ct":"avl_unit",
					"c":6883
				}
			},
			"repmax":-1,
			"uacl":-1
		}
	]
}

Обратим внимание на следующие параметры из ответа:

• nm — имя ресурса;

• rep — массив шаблонов отчетов, созданных в ресурсе;

  Если данный параметр отображается пустым, то это означает, что в ресурсе не создано шаблонов отчетов.

• n — имя подэлемента;
• id — системный ID.

В данном случае пользователю доступен ресурс sdk_account с системным ID 12345678, в котором находится шаблон отчета Список поездок с системным ID 1.

3. Выполнение отчета

Используем запрос report/exec_report.

https://hst-api.wialon.com/wialon/ajax.html?svc=report/exec_report¶ms={"reportResourceId":12345678,"reportTemplateId":1,"reportObjectId":55555,"reportObjectSecId":0,"interval":{"flags":0,"from":1688144400,"to":1688173199},"remoteExec":1}&sid=ИДЕНТИФИКАТОР_СЕССИИ

{
	"remoteExec":1
}

4. Проверка статуса выполнения

Так как отчет выполняется в фоновом режиме на сервере, то проверим статус его выполнения, используя запрос report/get_report_status.

https://hst-api.wialon.com/wialon/ajax.html?svc=report/get_report_status¶ms={}&sid=ИДЕНТИФИКАТОР_СЕССИИ

{
	"status":4
}

Код статуса 4 означает, что отчет выполнен. Интерпретацию остальных значений можно найти на странице с описанием запроса.

5. Получение результата отчета

Используем запрос report/apply_report_result.

https://hst-api.wialon.com/wialon/ajax.html?svc=report/apply_report_result¶ms={}&sid=ИДЕНТИФИКАТОР_СЕССИИ

{
	"reportResult":{
		"msgsRendered":0,
		"stats":[],
		"tables":[
			{
				"name":"unit_trips",
				"label":"Поездки",
				"grouping":{},
				"flags":4224,
				"rows":4,
				"level":1,
				"columns":5,
				"header":[
					"№",
					"Начало",
					"Конец",
					"Длительность",
					"Пробег"
				],
				"header_type":[
					"",
					"time_begin",
					"time_end",
					"duration",
					"mileage"
				]
			}
		],
		"attachments":[]
	}
}

Три ключевых параметра из ответа, интересующих нас, выглядят следующим образом:

• tables — показывает количество таблиц в отчете в виде массива. В данном случае упоминается только одна таблица — Поездки, следовательно, ее индекс будет равен 0.
• rows — количество строк в таблице, в данном случае их 4. Следовательно, их индексы лежат в диапазоне от 0 до 3.
• level — количество уровней вложенности, в данном случае оно равно 1, так как в отчете отсутствует группировка.

Также можно коротко перечислить другие параметры из ответа. Параметр columns говорит о количестве столбцов, далее их имена описаны в параметре header. Нулевое значение параметра msgsRendered говорит о том, что в шаблоне отчета не включено отображение сообщений на карте. Пустые параметры stats и attachments говорят о том, что в шаблоне отчета отсутствует Статистика и приложения (например, графики).

6. Получение строк таблицы

Зная индекс содержимого таблицы, отобразим ее, используя запрос report/get_result_rows.

https://hst-api.wialon.com/wialon/ajax.html?svc=report/get_result_rows¶ms={"tableIndex":0,"indexFrom":0,"indexTo":3}&sid=ИДЕНТИФИКАТОР_СЕССИИ

[
	{
		"n":0,
		"i1":0,
		"i2":790,
		"t1":1688144420,
		"t2":1688154878,
		"d":0,
		"c":[
			"1",
			{
				"t":"2023-06-30 20:00:20",
				"v":1688144420,
				"y":47.2941741943,
				"x":26.4906959534,
				"u":55555
			},
			{
				"t":"2023-06-30 22:54:38",
				"v":1688154878,
				"y":43.8697662354,
				"x":26.0177116394,
				"u":55555
			},
			"2:54:18",
			"469.54 км"
		]
	},
	{
		"n":1,
		"i1":936,
		"i2":2171,
		"t1":1688155181,
		"t2":1688169690,
		"d":0,
		"c":[
			"2",
			{
				"t":"2023-06-30 22:59:41",
				"v":1688155181,
				"y":43.8698196411,
				"x":26.0177154541,
				"u":55555
			},
			{
				"t":"2023-07-01 03:01:30",
				"v":1688169690,
				"y":41.7139854431,
				"x":26.3660545349,
				"u":55555
			},
			"4:01:49",
			"343.84 км"
		]
	},
	{
		"n":2,
		"i1":2340,
		"i2":2486,
		"t1":1688170034,
		"t2":1688170841,
		"d":0,
		"c":[
			"3",
			{
				"t":"2023-07-01 03:07:14",
				"v":1688170034,
				"y":41.7140579224,
				"x":26.365901947,
				"u":55555
			},
			{
				"t":"2023-05-01 09:23:10",
				"v":1688170841,
				"y":41.7122383118,
				"x":26.3712425232,
				"u":55555
			},
			"0:13:27",
			"1.39 км"
		]
	},
	{
		"n":3,
		"i1":2833,
		"i2":2910,
		"t1":1688171565,
		"t2":1688173175,
		"d":0,
		"c":[
			"4",
			{
				"t":"2023-07-01 03:32:45",
				"v":1688171565,
				"y":41.7120819092,
				"x":26.3711204529,
				"u":55555
			},
			{
				"t":"2023-07-01 03:59:35",
				"v":1688173175,
				"y":41.5760040283,
				"x":26.9871864319,
				"u":55555
			},
			"0:26:50",
			"57.84 км"
		]
	}
]

7. Экспорт в файл

Экспортируем результат в PDF-файл, используя запрос report/export_result.

https://hst-api.wialon.com/wialon/ajax.html?svc=report/export_result¶ms={"format":2,"compress":0,"outputFileName":"Список%20поездок"}&sid=ИДЕНТИФИКАТОР_СЕССИИ

Ответ на данный API-запрос не отображается, вместо этого автоматически начинается загрузка файла.

8. Удаление результата предыдущего отчета

Используем запрос report/cleanup_result.

https://hst-api.wialon.com/wialon/ajax.html?svc=report/cleanup_result¶ms={}&sid=ИДЕНТИФИКАТОР_СЕССИИ

{
	"error":0
}

Нулевое значение означает успешное удаление.

Работа с отчетом с группировкой

Необходимо получить результаты выполнения отчета Поездки с группировкой, доступного авторизованному по токену пользователю, для объекта Грузовик 0769 (системный ID 55555) за интервал времени с 2023 Июнь 30 20:00 до 2023 Июль 01 03:59 (GMT+0) в виде ответа на API-запрос и PDF-файла.

В веб-интерфейсе результат выглядит следующим образом:

По результату выполнения в веб-интерфейсе видно, что таблица Поездки имеет группировку по месяцам и дате, то есть отчет имеет 3 уровня вложенности:

• на 1-м уровне расположены строки с месяцами;
• на 2-м — строки с датой в рамках месяца;
• на 3-м — строки непосредственно с поездками в рамках даты.

1. Авторизация и настройка локализации

Используем запрос token/login.

https://hst-api.wialon.com/wialon/ajax.html?svc=token/login¶ms={"token":"ЗНАЧЕНИЕ_ТОКЕНА"}

Более подробно авторизация описана в одной из предыдущих статей.

Настройка локализации включает в себя установку часового пояса (она также была рассмотрена ранее), формата даты и других параметров.

Используем запрос render/set_locale.

https://hst-api.wialon.com/wialon/ajax.html?svc=render/set_locale¶ms={"tzOffset":134217728,"language":"ru","formatDate":"%25E.%25m.%25Y%20%25H:%25M:%25S"}&sid=ИДЕНТИФИКАТОР_СЕССИИ

2. Получение системных ID

В одной из предыдущих статей мы уже описывали, как выполнять поиск элементов по критериям, поэтому сейчас обратим внимание только на поиск ресурса и шаблона отчета.

Получим список всех ресурсов, в которых создан шаблон отчета с именем Поездки с группировкой, доступных пользователю, для которого выполнена авторизация по токену. Используем запрос core/search_items:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"avl_resource","propType":"propitemname","propName":"reporttemplates","propValueMask":"Поездки%20с%20группировкой","sortType":"sys_name"},"force":1,"flags":8193,"from":0,"to":0}&sid=ИДЕНТИФИКАТОР_СЕССИИ

{
	"searchSpec":{
		"itemsType":"avl_resource",
		"propName":"reporttemplates",
		"propValueMask":"Поездки с группировкой",
		"sortType":"sys_name",
		propType:"propitemname",
		or_logic:"0"
		},
	"dataFlags":8193,
	"totalItemsCount":1,
	"indexFrom":0,
	"indexTo":0,
	"items":[
		{
			"nm":"sdk_account",
			"cls":3,
			"id":12345678,
			"mu":0,
			"rep":{
				1:{
					"id":1,
					"n":"Список поездок",
					"ct":"avl_unit",
					"c":59352
				},
				2:{
					"id":2,
					"n":"Поездки с группировкой",
					"ct":"avl_unit",
					"c":6883
				}
			},
			"repmax":-1,
			"uacl":-1
		}
	]
}

Обратим внимание на следующие параметры из ответа:

• nm — имя ресурса;

• rep — массив шаблонов отчетов, созданных в ресурсе;

  Если данный параметр отображается пустым, то это означает, что в ресурсе не создано шаблонов отчетов.

• n — имя подэлемента;
• id — системный ID.

В данном случае пользователю доступен ресурс sdk_account с системным ID 12345678, в котором находится шаблон отчета Поездки с группировкой с системным ID 2.

3. Выполнение отчета

Используем запрос report/exec_report.

https://hst-api.wialon.com/wialon/ajax.html?svc=report/exec_report¶ms={"reportResourceId":12345678,"reportTemplateId":2,"reportObjectId":55555,"reportObjectSecId":0,"interval":{"flags":0,"from":1688144400,"to":1688173199},"remoteExec":1}&sid=ИДЕНТИФИКАТОР_СЕССИИ

{
	"remoteExec":1
}

4. Проверка статуса выполнения

Так как отчет выполняется в фоновом режиме на сервере, то проверим статус его выполнения, используя запрос report/get_report_status.

https://hst-api.wialon.com/wialon/ajax.html?svc=report/get_report_status¶ms={}&sid=ИДЕНТИФИКАТОР_СЕССИИ

{
	"status":4
}

Код статуса 4 означает, что отчет выполнен. Интерпретацию остальных значений можно найти на странице с описанием запроса.

5. Получение результата отчета

Используем запрос report/apply_report_result.

https://hst-api.wialon.com/wialon/ajax.html?svc=report/apply_report_result¶ms={}&sid=ИДЕНТИФИКАТОР_СЕССИИ

{
	"reportResult":{
		"msgsRendered":0,
		"stats":[],
		"tables":[
			{
				"name":"unit_trips",
				"label":"Поездки",
				"grouping":{
					"nested":{
						"type":"day"
					},
					"type":"month"
				},
				"flags":4491,
				"rows":2,
				"level":3,
				"columns":6,
				"header":[
					"№",
					"Группировка",
					"Начало",
					"Конец",
					"Длительность",
					"Пробег"
				],
				"header_type":[
					"",
					"",
					"time_begin",
					"time_end",
					"duration",
					"mileage"
				]
			}
		],
		"attachments":[]
	}
}

Три ключевых параметра из ответа, интересующих нас, выглядят следующим образом:

• tables — показывает количество таблиц в отчете в виде массива. В данном случае упоминается только одна таблица — Поездки, следовательно, ее индекс будет равен 0.
• rows — количество строк в таблице, в данном случае их 2. Следовательно, их индексы лежат в диапазоне от 0 до 1. Речь идет только про строки на верхнем уровне вложенности, внутри их может быть больше.
• level — количество уровней вложенности, в данном случае оно равно 3, так как в отчете присутствует группировка. Следовательно, в таблице существуют уровни с индексами от 0 до 2.

Также можно коротко перечислить другие параметры из ответа. Параметр columns говорит о количестве столбцов, далее их имена описаны в параметре header. Нулевое значение параметра msgsRendered говорит о том, что в шаблоне отчета не включено отображение сообщений на карте. Пустые параметры stats и attachments говорят о том, что в шаблоне отчета отсутствует Статистика и приложения (например, графики).

6. Выбор строк в многоуровневой таблице

Зная индекс содержимого таблицы отобразим ее, используя запрос report/select_result_rows.

https://hst-api.wialon.com/wialon/ajax.html?svc=report/select_result_rows¶ms={"tableIndex":0,"config":{"type":"range","data":{"from":0,"to":1,"level":2}}}&sid=ИДЕНТИФИКАТОР_СЕССИИ

[
	{
		"n":0,
		"i1":0,
		"i2":1188,
		"t1":1688144420,
		"t2":1688158739,
		"d":1,
		"c":[
			"1",
			"Июнь",
			{
				"t":"20:00:20",
				"v":1688144420,
				"y":47.2941741943,
				"x":26.4906959534,
				"u":55555
			},
			{
				"t":"23:58:59",
				"v":1688158739,
				"y":43.1049079895,
				"x":25.6173667908,
				"u":55555
			},
			"3:53:36",
			"576.60 км"
		],
		"r":[
			{
				"n":0,
				"i1":0,
				"i2":1188,
				"t1":1688144420,
				"t2":1688158739,
				"d":2,
				"c":[
					"1.1",
					"2023-06-30",
					{
						"t":"20:00:20",
						"v":1688144420,
						"y":47.2941741943,
						"x":26.4906959534,
						"u":55555
					},
					{
						"t":"23:58:59",
						"v":1688158739,
						"y":43.1049079895,
						"x":25.6173667908,
						"u":55555
					},
					"3:53:36",
					"576.60 км"
				],
				"r":[
					{
						"n":0,
						"i1":0,
						"i2":790,
						"t1":1688144420,
						"t2":1688154878,
						"d":0,
						"c":[
							"1.1.1",
							"2023-06-30 20:00:20",
							{
								"t":"20:00:20",
								"v":1688144420,
								"y":47.2941741943,
								"x":26.4906959534,
								"u":55555
							},
							{
								"t":"22:54:38",
								"v":1688154878,
								"y":43.8697662354,
								"x":26.0177116394,
								"u":55555
							},
							"2:54:18",
							"469.54 км"
						]
					},
					{
						"n":1,
						"i1":936,
						"i2":1188,
						"t1":1688155181,
						"t2":1688158739,
						"d":0,
						"c":[
							"1.1.2",
							"2023-06-30 22:59:41",
							{
								"t":"22:59:41",
								"v":1688155181,
								"y":43.8698196411,
								"x":26.0177154541,
								"u":55555
							},
							{
								"t":"23:58:59",
								"v":1688158739,
								"y":43.1049079895,
								"x":25.6173667908,
								"u":55555
							},
							"0:59:18",
							"107.06 км"
						]
					}
				]
			}
		]
	},
	{
		"n":1,
		"i1":1193,
		"i2":2910,
		"t1":1688158805,
		"t2":1688173175,
		"d":1,
		"c":[
			"2",
			"Июль",
				{
					"t":"00:00:05",
					"v":1688158805,
					"y":43.0983314514,
					"x":25.6316585541,
					"u":55555
				},
				{
					"t":"03:59:35",
					"v":1688173175,
					"y":41.5760040283,
					"x":26.9871864319,
					"u":55555
				},
				"3:41:42",
				"294.55 км"
		],
		"r":[
			{
				"n":0,
				"i1":1193,
				"i2":2910,
				"t1":1688158805,
				"t2":1688173175,
				"d":3,
				"c":[
					"2.1",
					"2023-07-01",
					{
						"t":"00:00:05",
						"v":1688158805,
						"y":43.0983314514,
						"x":25.6316585541,
						"u":55555
					},
					{
						"t":"03:59:35",
						"v":1688173175,
						"y":41.5760040283,
						"x":26.9871864319,
						"u":55555
					},
					"3:41:42",
					"294.55 км"
				],
				"r":[
					{
						"n":0,
						"i1":1193,
						"i2":2171,
						"t1":1688158805,
						"t2":1688169690,
						"d":0,
						"c":[
							"2.1.1",
							"2023-07-01 00:00:05",
							{
								"t":"00:00:05",
								"v":1688158805,
								"y":43.0983314514,
								"x":25.6316585541,
								"u":55555
							},
							{
								"t":"03:01:30",
								"v":1688169690,
								"y":41.7139854431,
								"x":26.3660545349,
								"u":55555
							},
							"3:01:25",
							"235.31 км"
						]
					},
					{
						"n":1,
						"i1":2340,
						"i2":2486,
						"t1":1688170034,
						"t2":1688170841,
						"d":0,
						"c":[
							"2.1.2",
							"2023-07-01 03:07:14",
							{
								"t":"03:07:14",
								"v":1688170034,
								"y":41.7140579224,
								"x":26.365901947,
								"u":55555
							},
							{
								"t":"03:20:41",
								"v":1688170841,
								"y":41.7122383118,
								"x":26.3712425232,
								"u":55555
							},
							"0:13:27",
							"1.39 км"
						]
					},
					{
						"n":2,
						"i1":2833,
						"i2":2910,
						"t1":1688171565,
						"t2":1688173175,
						"d":0,
						"c":[
							"2.1.3",
							"2023-07-01 03:32:45",
							{
								"t":"03:32:45",
								"v":1688171565,
								"y":41.7120819092,
								"x":26.3711204529,
								"u":55555
							},
							{
								"t":"03:59:35",
								"v":1688173175,
								"y":41.5760040283,
								"x":26.9871864319,
								"u":55555
							},
							"0:26:50",
							"57.84 км"
						]
					}
				]
			}
		]
	}
]

7. Экспорт в файл

Экспортируем результат в PDF-файл, используя запрос report/export_result.

https://hst-api.wialon.com/wialon/ajax.html?svc=report/export_result¶ms={"format":2,"compress":0,"outputFileName":"Поездки%20с%20группировкой"}&sid=ИДЕНТИФИКАТОР_СЕССИИ

Ответ на данный API-запрос не отображается, вместо этого автоматически начинается загрузка файла.

8. Удаление результата предыдущего отчета

Используем запрос report/cleanup_result.

https://hst-api.wialon.com/wialon/ajax.html?svc=report/cleanup_result¶ms={}&sid=ИДЕНТИФИКАТОР_СЕССИИ

{
	"error":0
}

Нулевое значение означает успешное удаление.

Особенности получения результатов

Получение данных из таблиц может осуществляться с помощью запросов report/get_result_rows или report/select_result_rows, в которых используется параметр tableIndex, чтобы обратиться к таблице с определенным индексом. При этом необходимо учитывать, что при выполнении отчета за разные интервалы индекс одной и той же таблицы может меняться из-за наличия или отсутствия других таблиц.

Для лучшего понимания ситуации рассмотрим пример. Предположим, что в шаблон отчета добавлены таблицы Поездки, Сливы и Геозоны. При выполнении отчета за интервал с 1 по 3 июля результат будет содержать все таблицы, а потому их индексы примут следующие значения:

0 — Поездки
1 — Сливы
2 — Геозоны

А при выполнении отчета за интервал с 4 по 6 июля индексы некоторых таблиц поменяются из-за отсутствия зарегистрированных сливов и примут другие значения:

0 — Поездки
1 — Геозоны

В данном примере хорошо видно, что при выполнении отчета за разные интервалы индекс таблицы Геозоны изменяется. Следовательно, обращение к таблице с индексом 2 не всегда будет выводить информацию о посещении геозон. Для исправления подобных ситуаций рекомендуется применять дополнительные проверки, например, по названию таблицы или ее столбцов.

Екатерина Гриб,Инженер Customer Service 2023-08-09

В данной статье собраны ответы на наиболее часто задаваемые вопросы касательно Remote API.

Существуют ли ограничения на использование API?

Глобальные ограничения описаны в документации. Как правило, достижение этих ограничений говорит о том, что разработанное приложение не оптимизировано под работу с API. Например, оно выполняет множественные запросы авторизации вместо того, чтобы поддерживать одну сессию активной.

Ограничения существуют и у некоторых запросов, они упоминаются в описании запроса в документации. Например, одновременно в сессии может быть выполнен только один отчет. Если в сессии содержатся результаты выполнения предыдущего отчета, то их следует удалить с помощью запроса report/cleanup_result перед выполнением следующего отчета. Также запрос на выполнение отчетов не может выполняться одновременно с некоторыми другими запросами.

Можно ли с помощью API организовать передачу данных из Wialon в реальном времени?

Нет. API-запросы работают по принципу «запрос-ответ». То есть данные на принимающей стороне не будут обновляться без отправления запроса.

Если необходимо получать данные от оборудования по мере поступления новых сообщений, то можно использовать ретрансляторы.

Как создать локатор через API?

Рассмотрим пример: необходимо создать локатор с неограниченным сроком действия, на котором будут отображаться объекты с системным ID 11111111 и 22222222, а также геозоны из ресурса с системным ID 12345678, но не будут отображаться треки объектов.

Для этого нужно использовать запрос token/update:

https://hst-api.wialon.com/wialon/ajax.html?svc=token/update¶ms=
{"callMode":"create","app":"locator","at":0,"dur":0,"fl":256,"p":"{\"note\":\"Bus\",\"zones\":1,\"tracks\":0}","items":[11111111,22222222,12345678]}&sid=ИДЕНТИФИКАТОР_СЕССИИ

В ответе на запрос будет присутствовать параметр h, содержащий значение токена. Для получения искомой ссылки необходимо подставить значение токена в ссылку: https://hosting.wialon.com/locator/index.html?t=ЗНАЧЕНИЕ_ТОКЕНА

Как получить токен с максимальным доступом и без ограничения срока жизни?

Если создание токена осуществляется через расширенную форму, то необходимо использовать параметры access_type=-1 и duration=0. Например:

https://hosting.wialon.com/login.html?client_id=ИМЯ_ПРИЛОЖЕНИЯ&access_type=-1&activation_time=0&duration=0&lang=ru&flags=0&user=ИМЯ_ПОЛЬЗОВАТЕЛЯ

Если создание токена осуществляется через запрос token/update, то необходимо использовать параметры fl=-1 и dur=0. Например:

https://hst-api.wialon.com/wialon/ajax.html?svc=token/update¶ms=
{"callMode":"create","app":"Wialon Hosting","at":0,"dur":0,"fl":-1,"p":"{}"}&sid=ИДЕНТИФИКАТОР_СЕССИИ

Почему при использовании бессрочного токена может возвращаться ошибка с кодом 1?

Ошибка с кодом 1 говорит о том, что текущая сессия недействительна. Срок жизни токена не связан с сессией напрямую.

Для исправления ситуации необходимо повторно выполнить авторизацию. В ответе на логин под токеном будет содержаться параметр eid, значение которого является уникальным идентификатором сессии. Далее он будет использоваться практически во всех API-запросах.

Как исправить ошибку с кодом 4?

Ошибка с кодом 4 соответствует неверному вводу, что может означать:

• неправильный тип данных (числовой, текстовый и т. д.);

• неправильные имена параметров;
• неправильные разделители (запятые, кавычки, пробелы, скобки и т. п.);
• отсутствие кодировки для передачи в URL.

Рассмотрим пример запроса со всеми обозначенными ошибками:

https://hst-api.wialon.com/wialon/ajax.html?svc=report/export_result¶ms={"format":"2";"compres":0;"outputFileName":"Список поездок"}&sid=ИДЕНТИФИКАТОР_СЕССИИ

В данном примере были допущены следующие ошибки:

1. параметр format должен содержать число, но так как его значение указано в кавычках, то оно воспринимается, как текст;
2. вместо параметра с именем compress использовался параметр с именем compres;
3. для разделения параметров вместо запятой использовалась точка с запятой;
4. символ пробела не был закодирован для передачи в URL.

Правильный запрос будет выглядеть следующим образом:

https://hst-api.wialon.com/wialon/ajax.html?svc=report/export_result¶ms={"format":2,"compress":0,"outputFileName":"Список%20поездок"}&sid=ИДЕНТИФИКАТОР_СЕССИИ

Почему при использовании уникальных ID объектов возникает ошибка с кодом 7?

В API-запросах используются не уникальные ID объектов с вкладки Основное, а внутренние системные ID элементов. По умолчанию они не отображаются в веб-интерфейсах.

Чтобы получить системные ID элементов, можно использовать запрос поиска элементов по критериям (core/search_items). В ответе на данный запрос в параметре id будет находиться искомое значение.

Почему доступ к элементу ограничен, хотя пользователь имеет полные права?

Вероятно, проблема возникает из-за нехватки прав у используемого токена.

Для проверки прав токена выполните логин под ним:

https://hst-api.wialon.com/wialon/ajax.html?svc=token/login¶ms={"token":"ЗНАЧЕНИЕ_ТОКЕНА"}

В ответе будет содержаться параметр fl, который отображает текущие права токена. Чтобы их изменить, отредактируйте текущий токен или создайте новый.

Как получить последние координаты объектов?

Для получения последних координат от нескольких объектов можно использовать запрос поиска элементов по критериям (core/search_items). При этом необходимо указать флаги доступа, согласно которым в ответе отобразятся имена объектов ("flag":1") и информация о последнем местоположении объектов ("flag":1024). Флаги можно суммировать между собой, поэтому в запросе будет использоваться значение 1 + 1024 = 1025.

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"avl_unit","propName":"sys_name","propValueMask":"*","sortType":"sys_name"},"force":1,"flags":1025,"from":0,"to":0}&sid=ИДЕНТИФИКАТОР_СЕССИИ

Как получить список всех доступных пользователю объектов?

Для вывода всех доступных пользователю объектов можно использовать запрос поиска элементов по критериям (core/search_items) со значением "propValueMask":"*".

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"avl_unit","propName":"sys_name","propValueMask":"*","sortType":"sys_name"},"force":1,"flags":1,"from":0,"to":0}&sid=ИДЕНТИФИКАТОР_СЕССИИ

В ответе вернется список объектов, которые доступны тому пользователю, чей идентификатор сессии использовался в запросе.

Как получить имена групп, в которые включен определенный объект?

Чтобы получить имена групп, в которые входит объект с системным ID 11112222, необходимо использовать запрос поиска элементов по критериям (core/search_items) со значениями "itemsType":"avl_unit_group", "propName":"sys_units" и "propType":"list".

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"avl_unit_group","propName":"sys_units","propValueMask":11112222,"sortType":"sys_name","propType":"list"},"force":1,"flags":1,"from":0,"to":0}}&sid=ИДЕНТИФИКАТОР_СЕССИИ

Как получить имена объектов из определенной группы?

Чтобы получить имена объектов, которые входят в группу с именем Group, необходимо использовать два запроса поиска элементов по критериям (core/search_items): первый будет искать по группе объектов (avl_unit_group), а второй — по объекту (avl_unit).

1. Сначала нужно получить список системных ID объектов, которые входят в группу (ее имя нужно указать в параметре propValueMask):

   https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"avl_unit_group","propName":"sys_name","propValueMask":"Group","sortType":"sys_name"},"force":1,"flags":1,"from":0,"to":0}&sid=ИДЕНТИФИКАТОР_СЕССИИ

    Ответ

   {
   	"searchSpec":{
   		"itemsType":"avl_unit_group",
   		"propName":"sys_name",
   		"propValueMask":"Group",
   		"sortType":"sys_name",
   		"propType":"",
   		"or_logic":"0"
   	},
   	"dataFlags":1,
   	"totalItemsCount":1,
   	"indexFrom":0,
   	"indexTo":0,
   	"items":[
   		{
   			"nm":"Group",
   			"cls":5,
   			"id":10000000,
   			"mu":0,
   			"u":[
   				20000001,
   				20000002,
   				20000003
   			],
   			"uacl":-1
   		}
   	]
   }
   

2. В ответе на предыдущий запрос необходимо найти параметр u с системными ID объектов. Их нужно подставить в параметр propValueMask для следующего запроса поиска:
   

   https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"avl_unit","propName":"sys_id","propValueMask":"20000001,20000002,20000003","sortType":"sys_name"},"force":1,"flags":1,"from":0,"to":0}&sid=ИДЕНТИФИКАТОР_СЕССИИ

    Ответ

   {
   	searchSpec:{
   		itemsType:"avl_unit",
   		propName:"sys_id",
   		propValueMask:"20000001,20000002,20000003",
   		sortType:"sys_name",
   		propType:"",
   		or_logic:"0"
   	},
   	dataFlags:1,
   	totalItemsCount:3,
   	indexFrom:0,
   	indexTo:0,
   	items:[
   		{
   			nm:"Unit_1",
   			cls:2,
   			id:20000001,
   			mu:0,
   			uacl:-1
   		},
   		{
   			nm:"Unit_2",
   			cls:2,
   			id:20000002,
   			mu:0,
   			uacl:-1
   		},
   		{
   			nm:"Unit_3",
   			cls:2,
   			id:20000003,
   			mu:0,
   			uacl:-1
   		}
   	]
   }
   

   Имена объектов будут отображаться в параметрах nm.

Почему отличаются результаты отчета в интерфейсе и в ответе на API-запрос?

При выполнении отчетов через API-запросы важно не забыть настроить часовой пояс для текущей сессии. Для этого сразу после авторизации следует однократно применить настройки локализации пользователя.

Екатерина Гриб,Инженер Customer Service 2023-08-25